Discovery and header additions for the experiment description (Stage 1, PR 6) - #190

Summary

Stage 1 design PR 6 (design §1 card 2, §3 modules, §5 row 6). Additive and behaviour-preserving; nothing in the notebook or CLI uses it yet.

• NFC and mask-type names (only with a description, owner decision Q1). preflight(..., with_description=True) (also remasked, find_masks) refuses:
  • a condition, repeat or technical-repeat folder that is not Unicode NFC: R_FOLDER_NOT_NFC;
  • a discovered mask type that breaks the Label rules (NA, cells): R_MASK_TYPE_NAME_INVALID;
  • a mask type that is not NFC: R_FOLDER_NOT_NFC.
    Nothing is renamed or normalized. Without a description (the default) these names are accepted exactly as in v0.4. New module name_issues.
• Raw header channel names. TiffMetadata.raw_channel_names and FileEntry.raw_channel_names hold the names as read, untrimmed. channel_names stays trimmed, same_source ignores the new field, and the manifest file entry gains the optional key raw_channel_names, written only when the header names a channel. The OME header reading moved from metadata.py to ome_header.py (the file-length baseline allows no growth).
• Phase-aware progress. preflight(progress=cb) calls cb(phase, done, total, path) for the phases folders, headers (once per image), masks and acquisitions. run.phases.progress_text words them ("2/4 headers 120/480"). Progress changes nothing about the result (tested with and without bind_headers).

Decisions and deviations

• Q1 and Q7 as given. Time-lapses need no change here.
• The design lists the NFC check under discovery.py. I put the folder check in name_issues and apply it in preflight, because discovery.py is at its code-rules size baseline (609 lines) and may not grow. discover_experiment is unchanged; call name_issues.non_nfc_folders_issue(discovery.leaves) to run the check on a bare discovery.
• Not done (later PRs): the R_HEADER_CONTRADICTION comparison of P26 (PR 8), and notebook or CLI display of the progress. No wording for the new codes in the user guide yet, since no run uses them.
• Baseline tools/code_rules_baseline.json: metadata.py lines lowered 721 to 700 by --update-baseline. New modules got layers in pyproject.toml.

Part of the Stage 1 plan (PR 6 of 17; no issue number).

Tests

• New: tests/test_spec_discovery.py (conformance P21, the recorded part of P26, P29; run under the skip-is-failure gate) and tests/test_preflight_progress.py.
• On the old src, 21 of the 24 new tests fail (for example test_p21_a_decomposed_folder_is_refused_with_a_description, test_p29_na_and_a_leading_space_are_invalid_mask_type_names, test_the_headers_phase_counts_every_image_with_its_path, test_raw_names_round_trip_through_the_manifest). The 3 that pass are the "without a description behaves as v0.4" tests, as intended.
• python tools/check.py: ruff check and format clean, code rules clean, 3570 passed, 4 skipped. The skips are environment-only and also skip on main: case-insensitive file system checks (3) and a root-permissions test (1). The legacy suite (3546 tests) is unchanged and passes.

Notes for review

• Expect a merge conflict in CHANGELOG.md only, with Description publication: lock, base SHA, symlink refusal, transitions, records (Stage 1, PR 5) #188 and Turn content hashing of the sources on by default #189.
• Raw names are the header text as read. A name that is not text is None, and the tuple is empty when no channel has a text name. A whitespace-only name is therefore kept in raw_channel_names but is unnamed in channel_names.
• Not exercised: macOS or Windows file systems (the P21 tests use one decomposed folder, never a composed and a decomposed pair, so they do not depend on case or normalization behaviour of the file system).

Generated by Claude Code